EnigmA Amiga Run 1996 June/EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso/earcd/utilsys/recorder.lha/Recorder.doc

Text File | 1996-05-08 | 16KB | 375 lines

                  Recorder V1.3
                  -------------

                  Released May, 8th 1996


           Written and Copyright ©1991/1996 by Oliver Grimm




  1. COPYRIGHT
  ============

  Both the program 'Recorder' and this documentation are copyrighted
  by me, but they are public domain software. That means you can use
  and spread them legally without paying any contributions (But I wouldn't
  reject them, too ..) as long as everything remains unmodified, only
  the complete archive, program plus documention, is distributed, and
  if you don't use the program commercially without my explicit permission
  (Please contact me in that case. My address can be found at the end of
  this text.)



  2. DISCLAIMER
  =============

  As usual, no warranty for anything ...



  3. INTRODUCTION
  ===============

  Whenever you hit a key, move the mouse, insert or remove a disk,
  resize a window, or basically make any kind of input to your computer,
  the operating system creates something that is called an 'input event'.
  That's a structure that is sent to all programs that wish to be informed
  about those things, and it includes all the information about your
  action, ie. the number of the key that you have pressed, the new
  position of your mouse pointer if the mouse has been moved, and so on.

  Now imagine you have to repeat the same input several times, eg. you
  have to type certain commands or click certain gadgets in a specific
  order, and there is, for some reason, no way in which you could
  automate this, by writing a script, for instance.

  Here, this program could help you. You could start Recorder, do your
  input once, and this program would save all the input events that have
  been generated by you in a file. Then you could play back all these
  inputs, and to all applications it will look like you are doing
  all inputs again, but actually they are 'fed' into the operating
  system by Recorder.



  4. USAGE
  ========

  Recorder has no GUI, so you have to start it from a command shell.
  The general parameter pattern of the program is the following, where
  parameters in [] are optional and (..|..|..) means you can (and must)
  choose one of the options in parentheses:


    Recorder (Rec|Play|App) [Quick] [NoWait] [Terse] [Pri n] FILENAME

  All options excep 'Pri n' can be abbreviated by their first letter.


  The basic operating mode is determined by one of the following:

    Rec         Record incoming input events and store them in the file with
         the name FILENAME.

    Play     Play input events stored in the file FILENAME.

    App      First play input events stored in the file FILENAME, then
         record more and append them to this file.
         Note that if you terminate play back early in this mode, you
         can't add more events, ie. Recorder just quits in that case.


   Note:   The event file format has changed since version 1.2 (See
   -----   section 9 for the reason.). If you try to play an old file,
       Recorder will tell you it's not a valid event file.



  The meaning of the options is as follows:

    Quick    If you choose play or append, the input events are normally
             played at the same speed as they were recorded. However, if
         you specify this option, events are played back as fast as
             possible, with no delay between them. See below for a warning
         about this option.
         This option is ignored in Rec mode.

    NoWait   If you specify this option, recording or play back will start
         immediately, so you don't have to press the control sequence
         given below first.
         In append mode, recording after play back will also start
         immediately.

    Terse    Recording some mouse movements, you will notice that the
         mouse pointer usually hoovers around doing nothing most of
         the time. With this option, Recorder will join together
         these unnecessary events, making the pointer movement not
         only much straighter, but also reducing the size of the
         event file considerably (because LOTS of mouse move events
         are usually generated). See section 6 for more info.
         This option is ignored in Play mode.

    Pri n    You can specify the priority of the input handler here. The
         default is 80.

         BEWARE: This is a dangerous option. Especially too low a
             priority might effectively cut off Recorder. The
             program will start normally, but it might be
             impossible to stop it again since the control sequence
             doesn't get to the handler anymore.
             USE THIS OPTION WITH CARE OR LEAVE IT ALONE.


  Unless you specify the 'NoWait' option, recording or playing will not
  begin immediately after the program has been started, but after you've
  pressed the key sequence Control-Left Amiga-'s'.
  You stop recording and, if you don't want to play everything back,
  also play back with the same sequence.

  If you want Recorder to play the next event right away, you can press
  the 'Return' key. The effect is similar to the 'Quick' option, but
  only affects one event. This function is especially usefull if you've
  recorded something with the 'Terse' option (see section 6).
  Note well that you only jump to the next event. Sometimes you might
  not see much effect. For example, you can hardly speed up mouse
  movements this way.

  It might happen that you start Recorder, and then, after a while, you
  aren't sure anymore if you actually started recording already or not.
  In that case you can press the key sequence Control-Left Amiga-'d'.
  If the program is currently recording (or playing back, but then it
  should be obvious), it will give out a display beep, but it won't do
  so if it is still waiting for the start sequence.
  Also, if you've started Recorder and try to start it again, it will
  refuse to do so and tell you that it's already running. This avoids
  that things are getting messed up if two input handlers interfere with
  each other (see section 7 for a bit more detail about this).

  You will notice that mouse and keyboard are locked in playback mode,
  ie. you can't make any inputs yourself. That's some sort of 'precaution',
  so that you don't accidentally interfere with play back. Of course, it's
  easy not to hit a key without intention, but it's not that easy with the
  mouse, and, as mentioned below in section 5, often mousemove events give
  only relative position, so if you would move the mouse yourself, the
  mouse position might in the following not be the same as it was during
  recording, and, for example, a gadget might be missed.

  A further note about the 'Quick' option: Because often a recorded
  event will result in some other action, for example, if you type a name
  of a program that you want to start, the 'Return' event that's generated
  when you confirm your input with the return key will result in this
  program to start, which will take some time. If you make some more input
  after the program has started, like clicking some gadget in that program,
  and if you play back the whole thing later with the 'Quick' option, you
  might get surprised. Depending on the speed of your computer, Recorder
  might already feed in the clicking of the gadget before the program has
  actually finished starting up. Of course, this is undesirable.
  So be careful with this option !

  Since Recorder always works in the background, there are not many ways
  to communicate with the user without disturbing other programs.
  Therefore, whenever Recorder wants to inform you about something, it
  sends a 'Display Beep' to all screens, which will make them blink, and,
  depending on your system preferences, you will also hear a beep.
  It does so under the following circumstances:

    1) Whenever you press the start/stop sequence to start or stop
       action to acknowlege your command.

    2) When you press Control-Left Amiga-'d' and Recorder is currently
       recording or playing.

    3) When play back has finished. In append mode that means that
       the program is now either waiting for the control sequence
       to start recording again, or that recording has just started
       again, depending on the 'NoWait' option.

    4) When the second internal buffer is full and the first one
       isn't written to the file yet. Then the program terminates,
       and the events in the internal buffers are saved.
       However, this should usually never happen, even if you are
       writing to a floppy disk (see section 8).



  5. WHAT DOES RECORDER RECORD ?
  ==============================

  Not all possible input events are recorded - it wouldn't make any
  sense to record and play back a 'disk inserted' event, when there
  actually hasn't been a disk inserted !
  In fact, all that is recorded are keyboard, mousemove and mousebutton
  events, so when you click a 'Load File' gadget in a program, you
  still have to insert the disk yourself ! So far, Recorder can't
  simulate that.
  Actually, sometimes Recorder does record an event which hasn't really
  happend. It is generated by Recorder whenever you start recording.
  You might have noticed that the mouse pointer usually 'jumps' when
  you start play back. This is so because a lot of events generated
  by moving the mouse only give relative positions, ie. the distance
  from the last mouse position. Therefore it is necessary that the mouse
  pointer is, at the beginning of playback, at the same position as it
  was at the beginning of recording. This is also the main reason why
  you can't make any inputs while Recorder is playing.
  In 'Terse' mode, a mousemove event is sometimes changed from relative
  to absolute type (see next section).



  6. MORE ABOUT THE 'TERSE' OPTION
  ================================

  The philosophy behind this option is that moving the mouse pointer
  usually doesn't mean anything if no other key or button is pressed at
  the same time (If some button is pressed, this might well mean something.
  Just draw something in a paint program.) That is, mouse movements are
  often very sloppy, you don't move the mouse in a straight line to its
  destination (Which is good because it shows that you are not a machine.),
  but you 'search', and maybe hesitate. If you play back something that
  has been recorded  without the 'Terse' option, you will see what I mean.

  Specifying this option makes Recorder effectively omit these 'search'
  movements. The program determines the total distance the mouse has moved
  between two events that did incorporate some keys or buttons, and then
  generates only one absolute mouse event that gives the new absolute
  postion. This means that in this case the type of an event is changed,
  from relative to absolute mouse postion. It's not possible to simply add
  up all relative events and generate one of the same type with the sum
  of them all, because a lot of people, including me, use a 'mouse
  accelerator', which means that it is not the same moving the mouse
  two times 10 pixels or moving it once twenty pixels.
  However, this changing of type shouln't make any problems, at least I
  haven't encountered any so far.

  Using this option alone won't speed up play back, because although the
  pointer movements are a lot quicker and more straight forward now,
  the program is still waiting the original time between key and button
  events (Unless you specify 'Quick'.), because speeding up the mouse
  does unfortunately not speed up your computer. So it will happen quite
  often that after the mouse pointer has moved quickly to some gadget,
  nothing will happen for a while. In that case you might find the 'Return'
  key quite usefull, as described above in section 4.



  7. COMPATIBILITY & PROBLEMS
  ===========================

  The program should work on all Amiga's with at least OS2.0.

  Possibly, there might be some interference with other input event
  modifying programs, such as those multi-functional commodities.
  I experienced one problem with AutoCLI V2.19 (If you hit the right
  mouse button after play back, the mouse pointer freezes. It 'melts'
  again if you hit the button again. If you press some other key in
  between, this problem vanishes.), about which I couldn't do anything
  so far.

  Also, I've been reported that activation of the file-gadget with the
  return key in Directory Opus does not work. I can't fix this.
  It might me that DOpus isn't using the standard input event procedure,
  in which case Recorder naturally fails.

  Currently the maximum time between two events is 10 years. This
  shouldn't be too much of a limitation, I think.



  8. HOW DOES IT WORK
  ===================

  This program installs, by means of the input device, an input handler
  at high priority (80, if you don't change it with the 'Pri' option),
  so that all input events pass through this handler (If there is no
  input handler at higher priority which might filter some events).
  These events are passed through unmodified, but also stored first
  in a memory buffer and eventually in a file. The program actually
  uses two buffers, and if one fills up the other one is used while the
  first one is stored on disk, so that continuous recording is possible.
  Should it happen that the second buffer fills up before the first one
  has been written to the file, recording is terminated, and all the
  so far recorded events are saved.
  However, each buffer can hold about 1000 events, and an overflow
  shouldn't occur, even if one writes to disk and moves the mouse
  rapidly.
  In play back mode, the stored events are fed into the input stream
  by the same handler.
  This handler also deals with the various control sequences, and tells
  the main program about them.



  9. PROGRAM HISTORY
  ==================

  First of all, thanks to the people who told me about bugs and suggested
  new features, especially to Ashley Powell and Simon Dainty (Who also
  did the beta testing for version 1.3) !


  Version 1.0 (March 1991)

    - First program version; I can't remember if I published this one ?!

  Version 1.1 (March 1996)

    - Implemented two event buffers
    - The position of the mouse pointer at the beginning of recording
      is now stored and set in play back.
    - General revision of the program (after all those years ...).

  Version 1.2 (March 1996) - Released.

    - Implemented automatic detaching from shell.

  Version 1.3 (April 1996)

    - Keyboard and mouse are now locked in playback, so you can't screw
      things up by accidently mouse the mouse.
    - Recorder sometimes or always crashed when stopped in playback mode.
      Fixed that.
    - Recorder is now checking if it has already been started.
    - The start/stop sequence is now filtered out to prevent interference
      with other programs that do not ignore this sequence.
    - Changed the whole command line parsing (now uses the function
      ReadArgs() of dos library). This results in a new (better, I'd say ..)
      command line format.
    - Added the opportunity to change the priority of the input handler
      with the 'Pri' option. However, this might be dangerous (see above).
    - Changed the way the timing is done. This results in slightly shorter
      event files (One event now uses 22 instead of 26 Bytes.), which also
      makes older event files incompatible. Also, the 'Quick' option will
      play quicker now.
    - Added 'NoWait' option, so that recording/playing might start
      immediately.
    - Added the possibility to check if recording has already been
      initiated by pressing Ctrl-Left Amiga-'d'.
    - Added 'Terse' recording mode.
    - If RETURN is pressed in play back mode, Recorder will now play the
      next event immediately, ie. it will skip the current delay.
    - Recorder always missed one event when the internal buffers where
      changed. Fixed that.



             ----------------------




  If you have any suggestions or find any bugs or, of course, would like
  to send me any postcards (!) or gifts (!!), here's my address:


        Oliver Grimm
        Steinbecker Str.69
        21244 Buchholz
           Germany

            E-Mail:  [e-mail]